﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IMarkupExtensionParser.cs" company="Xamlr">
//   The MIT License (MIT)
//   
//   Copyright (c) 2014 Brian Tyler
//   
//   Permission is hereby granted, free of charge, to any person obtaining a copy
//   of this software and associated documentation files (the "Software"), to deal
//   in the Software without restriction, including without limitation the rights
//   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//   copies of the Software, and to permit persons to whom the Software is
//   furnished to do so, subject to the following conditions:
//   
//   The above copyright notice and this permission notice shall be included in
//   all copies or substantial portions of the Software.
//   
//   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//   THE SOFTWARE.
// </copyright>
// <summary>
//   Defines the IMarkupExtensionParser type.
// </summary>
// --------------------------------------------------------------------------------------------------------------------

namespace Xamlr.Core.Markup
{
    using System;

    using JetBrains.Annotations;

    /// <summary>
    /// A markup extension parser.
    /// </summary>
    internal interface IMarkupExtensionParser
    {
        /// <summary>
        /// Tries to parse <paramref name="sourceText"/> and returns a value indicating success. 
        /// </summary>
        /// <param name="sourceText">
        /// The source text.
        /// </param>
        /// <param name="result">
        /// The result.
        /// </param>
        /// <returns>
        /// A value indicating whether the source was successfully parsed.
        /// </returns>
        bool TryParse([NotNull] string sourceText, out IMarkupExtensionInfo result);

        /// <summary>
        /// Parses <paramref name="sourceText"/>. 
        /// </summary>
        /// <param name="sourceText">
        /// The source text.
        /// </param>
        /// <returns>
        /// The <see cref="MarkupExtensionInfo"/>.
        /// </returns>
        /// <exception cref="ArgumentNullException">
        /// Thrown when the source text is null.
        /// </exception>
        /// <exception cref="ArgumentException">
        /// Thrown when the source text is white space.
        /// </exception>
        /// <exception cref="FormatException">
        /// Thrown when the source text is not a well formed markup extension.
        /// </exception>
        IMarkupExtensionInfo Parse([NotNull] string sourceText);
    }
}